home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / c / db / RCS / db.man,v < prev    next >
Text File  |  1989-01-26  |  7KB  |  194 lines

  1. head     1.2;
  2. branch   ;
  3. access   ;
  4. symbols  ;
  5. locks    ; strict;
  6. comment  @@;
  7.  
  8.  
  9. 1.2
  10. date     89.01.26.16.49.40;  author douglis;  state Exp;
  11. branches ;
  12. next     1.1;
  13.  
  14. 1.1
  15. date     88.12.30.13.50.06;  author ouster;  state Exp;
  16. branches ;
  17. next     ;
  18.  
  19.  
  20. desc
  21. @@
  22.  
  23.  
  24. 1.2
  25. log
  26. @added numBuf option to documentation.
  27. @
  28. text
  29. @'\" $Header: /sprite/src/lib/c/db/RCS/db.man,v 1.1 88/12/30 13:50:06 ouster Exp Locker: douglis $ SPRITE (Berkeley)
  30. .so \*(]ltmac.sprite
  31. .HS Db lib
  32. .BS
  33. .SH NAME
  34. Db \- manipulate simple database files
  35. .SH SYNOPSIS
  36. .nf
  37. \fB#include    <db.h>\fR
  38.  
  39. int
  40. \fBDb_WriteEntry\fR(\fIfile, buffer, index, size, lockHow\fP)
  41.  
  42. int
  43. \fBDb_ReadEntry\fR(\fIfile, buffer, index, size, lockHow\fP)
  44.  
  45. int
  46. \fBDb_Open\fR(\fIfile, size, handlePtr, writing, lockWhen, lockHow, numBuf\fP)
  47.  
  48. int
  49. \fBDb_Put\fR(\fIhandlePtr, buffer, index\fP)
  50.  
  51. int
  52. \fBDb_Get\fR(\fIhandlePtr, buffer, index\fP)
  53.  
  54. int
  55. \fBDb_Close\fR(\fIhandlePtr\fP)
  56.  
  57. .SH ARGUMENTS
  58. .AS Db_LockWhen *handlePtr
  59. .AP char *file in
  60. The name of a database file on which to perform operations.
  61. .AP char *buffer "in/out"
  62. A pointer to the area from which or to which to transfer the record.
  63. .AP int index out
  64. Which record to access in a database operation.
  65. .AP int size in
  66. The size of a record.
  67. .AP Db_LockHow lockHow in
  68. Method to use when locking the database.
  69. .AP Db_Handle *handlePtr "in/out"
  70. A pointer to a ``database handle''.  
  71. .AP int writing in
  72. If non-zero, the database file is opened in write-only mode, otherwise in
  73. read-only mode.
  74. .AP Db_LockWhen lockWhen in
  75. Determines when to lock the database for long-term accesses.
  76. .AP int numBuf in
  77. Number of records to buffer when reading from database.
  78. .BE
  79. .SH DESCRIPTION
  80. These functions provide shared access to files containing
  81. arbitrary numbers of fixed-length records.  There are two ways to
  82. access the files.  The simplest way to access a database file is to
  83. use \fBDb_WriteEntry()\fR and \fBDb_ReadEntry()\fR to open the file,
  84. access a record, and close the file again.  An alternative method is
  85. to use \fBDb_Open()\fR to obtain a \fBhandle\fP for the file, use
  86. \fBDb_Put()\fR or
  87. \fBDb_Get()\fR to write or read entries, respectively, and use Db_Close() to
  88. close the file when it is no longer needed.  In this case, the
  89. \fInumBuf\fR
  90. argument is used to specify how many records to buffer internally when doing
  91. reads (it must be specified as 0 for writes).
  92. .PP
  93. The Db library provides a simple locking facility to allow shared
  94. access to files, built on top of the \fBflock()\fR system call.  Database
  95. files can be accessed without using locks, or using the standard
  96. \fBflock()\fR call in blocking or non-blocking mode.  Unfortunately, hosts
  97. can hold locks when they crash, so a program that performs a blocking
  98. lock could wait indefinitely 
  99. for a lock if no additional mechanism is used.  The Db library allows
  100. locks to time out, and it can optionally break a lock if the lock
  101. times out.  The time-out period is currently fixed.  The different
  102. options are specified by the Db_LockHow type:
  103. .DS
  104. .ta 1c 2c 3c 4c 5c 6c 7c 8c
  105. typedef enum {
  106.     \fBDB_LOCK_NO_BLOCK\fP,        /* return immediately with error */
  107.     \fBDB_LOCK_POLL\fP,            /* poll the lock; time out if necessary */
  108.     \fBDB_LOCK_WAIT\fP,            /* wait indefinitely */
  109.     \fBDB_LOCK_BREAK\fP,        /* poll, plus break the lock if needed */
  110.     \fBDB_LOCK_NONE\fP,            /* do not lock the file at all */
  111. } Db_LockHow;
  112. .DE
  113. .PP
  114. The \fBDb_WriteEntry()\fR and \fBDb_ReadEntry()\fR procedures take a Db_LockHow
  115. parameter to determine how to lock the database file the one time it
  116. is accessed.  In addition to  a Db_Lock parameter, \fBDb_Open()\fR takes a
  117. Db_LockWhen argument to specify when to perform the lock.  Generally,
  118. when a file is going to be read or written sequentially, one would
  119. like to lock 
  120. it before starting to do I/O and unlock it after finishing.  If a file
  121. is going to be accessed repeatedly over a long period of time,
  122. however, it should be opened once but locked only during each access.
  123. These options are \fBDB_LOCK_OPEN\fP and \fBDB_LOCK_ACCESS\fP, respectively.  If
  124. the file is never to be locked, then the Db_LockWhen argument may be
  125. specified as \fBDB_LOCK_NEVER\fP or the Db_LockHow argument may be specified
  126. as \fBDB_LOCK_NONE\fP.
  127. .PP
  128. \fBDb_WriteEntry()\fR and \fBDb_ReadEntry()\fR provide access to a single record.
  129. They take the \fIfilename\fP to access; an \fIindex\fP into the file,
  130. the \fIsize\fP of a record; a pointer to a data \fIbuffer\fP;
  131. and the method of locking the database, \fIlockHow\fP.  All records
  132. must have the same size.  The index is zero-based, so \fIindex\fP 0
  133. refers to the first record in the file.
  134. .PP
  135. \fBDb_Open()\fR takes the same \fIfile\fP, \fIsize\fP, and \fIlockHow\fP
  136. arguments as \fBDb_WriteEntry()\fR and \fBDb_ReadEntry()\fR.  It also takes an
  137. argument, \fIwriting\fP, which indicates whether access will be
  138. writing (1) or reading (0); and another argument, \fInumBuf\fR, which
  139. specifies how many records to read from the file at once when doing
  140. reads.  The \fIlockWhen\fP argument is described 
  141. above; it indicates whether locking should be done for each access or at
  142. the time the file is opened.  \fBDb_Open()\fR returns a database handle in
  143. \fI*handlePtr\fP.  The storage for the handle must be allocated by the
  144. caller of \fBDb_Open()\fR.  A pointer to the handle must be used in later
  145. calls to \fBDb_Put()\fR, \fBDb_Get()\fR, or \fBDb_Close()\fR.
  146. .PP
  147. \fBDb_Put()\fR and \fBDb_Get()\fR are analogous to \fBDb_WriteEntry()\fR and
  148. \fBDb_ReadEntry()\fR.  They are used in cases when the database file is
  149. opened by \fBDb_Open()\fR, for use over an extended period of time.  The
  150. \fIhandlePtr\fP  argument must be a handle returned by \fBDb_Open()\fR. The
  151. \fIbuffer\fP  must be a pointer to an area of the size specified in the call
  152. to \fBDb_Open()\fR.  The \fIindex\fP  is an integer: if non-negative, it
  153. specifies a record number, like in calls to \fBDb_WriteEntry()\fR and
  154. \fBDb_ReadEntry()\fR.  If \fIindex\fP  is -1, it specifies that the access
  155. should be sequential: the
  156. record to be operated upon should be the one immediately following the
  157. last record read or written.  If \fBDb_Put()\fR
  158. or \fBDb_Get()\fR is called for the first time with an \fIindex\fP  of -1,
  159. the first record is written or read.
  160. .PP
  161. \fBDb_Close()\fR closes a file that was opened with \fBDb_Open()\fR.
  162. \fIHandlePtr\fP must point to a handle that was initialized by
  163. \fBDb_Open()\fR.
  164. .SH DIAGNOSTICS
  165. All routines return 0 if they complete successfully.  Upon error, they
  166. return -1 and the \fIerrno\fP variable  contains additional information
  167. about what error occurred.
  168. .SH KEYWORDS
  169. database, data base, lock, record, handle
  170. .SH SEE ALSO
  171. mig, ulog, flock, dbm
  172. @
  173.  
  174.  
  175. 1.1
  176. log
  177. @Initial revision
  178. @
  179. text
  180. @d1 1
  181. a1 1
  182. '\" $Header: Db,v 1.2 88/09/22 22:08:01 douglis Exp $ SPRITE (Berkeley)
  183. d18 1
  184. a18 1
  185. \fBDb_Open\fR(\fIfile, size, handlePtr, writing, lockWhen, lockHow\fP)
  186. d48 2
  187. d60 4
  188. a63 1
  189. close the file when it is no longer needed.  
  190. d110 3
  191. a112 1
  192. writing (1) or reading (0).  The \fIlockWhen\fP argument is described
  193. @
  194.